openapi: 3.0.1
info:
  title: Plan Rollouts API
  version: v1
servers:
  - url: https://api.rollouts.sb3.plannotice.com/
    description: Sandbox
  - url: https://api.planrollouts.com/
    description: Production
paths:
  /api/v1/OAuth/Token:
    post:
      tags:
        - OAuth
      summary: API Token
      description: Retrieves a token using client credentials provided by Plan Notice.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Auth0ClientCredentialsTokenRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/Auth0ClientCredentialsTokenRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/Auth0ClientCredentialsTokenRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auth0TokenSuccess'
  /api/v1/Participants:
    post:
      tags:
        - Participants
      summary: Request Rollout Notice
      description: >-
        This API submits a Participant Rollout Request to initiate the sending
        of a rollout notice.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Participant'
            examples:
              Standard Participant:
                value:
                  erisaEIN: 12-3456789
                  erisaPlanNumber: '001'
                  erisaPlanName: Plan 1
                  planSponsorCompany: ABC Company
                  externalReferenceId: '987654321'
                  reason: SBR
                  firstName: John
                  lastName: Smith
                  ssn: 123-45-6789
                  addressLine1: 123 Main St
                  addressLine2: Apt 4B
                  city: Anytown
                  state: CA
                  zip: '12345'
                  countryCode: US
                  totalBalance: 1000
                  vestedBalance: 10
                  balanceAsOf: '2025-11-04T12:56:13.1265208Z'
                  gracePeriod: 30
                  noticeLogoUrl: Add Your Notice Logo URL
                  noticeFileContentUrl: Add Your Notice File Content URL
                  helpName: Support Team
                  helpPhone: 555-555-5555
                  helpWebsite: www.support.com
                  helpEmail: help@support.com
                  helpAddressLine1: 123 Main St
                  helpAddressLine2: Apt 4B
                  helpCity: Anytown
                  helpState: CA
                  helpZip: '12345'
                  helpCountryCode: US
              Participant Without SSN:
                value:
                  erisaEIN: 89-0123456
                  erisaPlanNumber: '005'
                  erisaPlanName: Plan 2
                  planSponsorCompany: ABC Company
                  externalReferenceId: ABC123XYZ
                  reason: Transferred from Another Provider
                  firstName: Sarah
                  lastName: Williams
                  ssn: ''
                  addressLine1: 500 Sunset Blvd
                  addressLine2: Apt 10C
                  city: San Diego
                  state: CA
                  zip: '92101'
                  countryCode: US
                  totalBalance: 75000
                  vestedBalance: 10
                  balanceAsOf: '2025-11-04T12:56:13.1265215Z'
                  gracePeriod: 60
                  noticeLogoUrl: Add Your Notice Logo URL
                  noticeFileContentUrl: Add Your Notice File Content URL
                  helpName: Retirement Services
                  helpPhone: 877-456-7890
                  helpWebsite: www.retirehelp.com
                  helpEmail: support@retirehelp.com
                  helpAddressLine1: 123 Main St
                  helpAddressLine2: Apt 4B
                  helpCity: Anytown
                  helpState: CA
                  helpZip: '12345'
                  helpCountryCode: US
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Participant'
            examples:
              Standard Participant:
                value:
                  erisaEIN: 12-3456789
                  erisaPlanNumber: '001'
                  erisaPlanName: Plan 1
                  planSponsorCompany: ABC Company
                  externalReferenceId: '987654321'
                  reason: SBR
                  firstName: John
                  lastName: Smith
                  ssn: 123-45-6789
                  addressLine1: 123 Main St
                  addressLine2: Apt 4B
                  city: Anytown
                  state: CA
                  zip: '12345'
                  countryCode: US
                  totalBalance: 1000
                  vestedBalance: 10
                  balanceAsOf: '2025-11-04T12:56:13.1265208Z'
                  gracePeriod: 30
                  noticeLogoUrl: Add Your Notice Logo URL
                  noticeFileContentUrl: Add Your Notice File Content URL
                  helpName: Support Team
                  helpPhone: 555-555-5555
                  helpWebsite: www.support.com
                  helpEmail: help@support.com
                  helpAddressLine1: 123 Main St
                  helpAddressLine2: Apt 4B
                  helpCity: Anytown
                  helpState: CA
                  helpZip: '12345'
                  helpCountryCode: US
              Participant Without SSN:
                value:
                  erisaEIN: 89-0123456
                  erisaPlanNumber: '005'
                  erisaPlanName: Plan 2
                  planSponsorCompany: ABC Company
                  externalReferenceId: ABC123XYZ
                  reason: Transferred from Another Provider
                  firstName: Sarah
                  lastName: Williams
                  ssn: ''
                  addressLine1: 500 Sunset Blvd
                  addressLine2: Apt 10C
                  city: San Diego
                  state: CA
                  zip: '92101'
                  countryCode: US
                  totalBalance: 75000
                  vestedBalance: 10
                  balanceAsOf: '2025-11-04T12:56:13.1265215Z'
                  gracePeriod: 60
                  noticeLogoUrl: Add Your Notice Logo URL
                  noticeFileContentUrl: Add Your Notice File Content URL
                  helpName: Retirement Services
                  helpPhone: 877-456-7890
                  helpWebsite: www.retirehelp.com
                  helpEmail: support@retirehelp.com
                  helpAddressLine1: 123 Main St
                  helpAddressLine2: Apt 4B
                  helpCity: Anytown
                  helpState: CA
                  helpZip: '12345'
                  helpCountryCode: US
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Participant'
            examples:
              Standard Participant:
                value:
                  erisaEIN: 12-3456789
                  erisaPlanNumber: '001'
                  erisaPlanName: Plan 1
                  planSponsorCompany: ABC Company
                  externalReferenceId: '987654321'
                  reason: SBR
                  firstName: John
                  lastName: Smith
                  ssn: 123-45-6789
                  addressLine1: 123 Main St
                  addressLine2: Apt 4B
                  city: Anytown
                  state: CA
                  zip: '12345'
                  countryCode: US
                  totalBalance: 1000
                  vestedBalance: 10
                  balanceAsOf: '2025-11-04T12:56:13.1265208Z'
                  gracePeriod: 30
                  noticeLogoUrl: Add Your Notice Logo URL
                  noticeFileContentUrl: Add Your Notice File Content URL
                  helpName: Support Team
                  helpPhone: 555-555-5555
                  helpWebsite: www.support.com
                  helpEmail: help@support.com
                  helpAddressLine1: 123 Main St
                  helpAddressLine2: Apt 4B
                  helpCity: Anytown
                  helpState: CA
                  helpZip: '12345'
                  helpCountryCode: US
              Participant Without SSN:
                value:
                  erisaEIN: 89-0123456
                  erisaPlanNumber: '005'
                  erisaPlanName: Plan 2
                  planSponsorCompany: ABC Company
                  externalReferenceId: ABC123XYZ
                  reason: Transferred from Another Provider
                  firstName: Sarah
                  lastName: Williams
                  ssn: ''
                  addressLine1: 500 Sunset Blvd
                  addressLine2: Apt 10C
                  city: San Diego
                  state: CA
                  zip: '92101'
                  countryCode: US
                  totalBalance: 75000
                  vestedBalance: 10
                  balanceAsOf: '2025-11-04T12:56:13.1265215Z'
                  gracePeriod: 60
                  noticeLogoUrl: Add Your Notice Logo URL
                  noticeFileContentUrl: Add Your Notice File Content URL
                  helpName: Retirement Services
                  helpPhone: 877-456-7890
                  helpWebsite: www.retirehelp.com
                  helpEmail: support@retirehelp.com
                  helpAddressLine1: 123 Main St
                  helpAddressLine2: Apt 4B
                  helpCity: Anytown
                  helpState: CA
                  helpZip: '12345'
                  helpCountryCode: US
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeParticipantResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validation'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/Participants/status:
    get:
      tags:
        - Participants
      summary: Get Status
      description: "This API fetches the status of rollout notices based on Erisa EIN, Erisa Plan Number, SSN, and externalReferenceId.\r\n            At least one parameter (Erisa EIN, Erisa Plan Number, ssn, or externalReferenceId) must be provided.\r\n            If multiple parameters are used, they will be ANDed together to create the results."
      parameters:
        - name: erisaEin
          in: query
          description: The Erisa EIN associated with the rollout notice.
          schema:
            type: string
        - name: erisaPlanNumber
          in: query
          description: The Erisa Plan Number associated with the rollout notice.
          schema:
            type: string
        - name: ssn
          in: query
          description: The SSN associated with the rollout notice.
          schema:
            type: string
        - name: externalReferenceId
          in: query
          description: An external reference ID associated with the rollout notice.
          schema:
            type: string
        - name: skip
          in: query
          description: Number of records to skip before returning results.
          schema:
            type: integer
            format: int32
        - name: take
          in: query
          description: Maximum number of records to return.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NoticeParticipantsRequestStatusView'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
    post:
      tags:
        - Participants
      summary: Get Status
      description: >-
        This API fetches the status of notices based on Erisa EIN and Erisa Plan
        Number or date range.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantStatusViewModel'
            examples:
              Standard Request with ERISA EIN & ERISA Plan Number:
                value:
                  erisaPlanRecords:
                    - erisaEIN: 12-3456789
                      erisaPlanNumber: '001'
                    - erisaEIN: 98-7654321
                      erisaPlanNumber: '002'
                  from: '2025-10-05T12:56:13.1309707+00:00'
                  to: '2025-11-04T12:56:13.1309719+00:00'
                  skip: 0
                  take: 100
              Request with Date Range Only (No EIN/ERISA):
                value:
                  erisaPlanRecords: null
                  from: '2024-01-01T00:00:00'
                  to: '2024-12-31T00:00:00'
                  skip: 0
                  take: 100
              Single ERISA EIN & ERISA Plan Query:
                value:
                  erisaPlanRecords:
                    - erisaEIN: 45-6789012
                      erisaPlanNumber: '003'
                  from: '2025-09-05T12:56:13.1309728+00:00'
                  to: '2025-10-05T12:56:13.1309729+00:00'
                  skip: 0
                  take: 100
              Invalid Scenario - Missing Dates and ERISA Data:
                value:
                  erisaPlanRecords: []
                  from: null
                  to: null
                  skip: 0
                  take: 100
          text/json:
            schema:
              $ref: '#/components/schemas/ParticipantStatusViewModel'
            examples:
              Standard Request with ERISA EIN & ERISA Plan Number:
                value:
                  erisaPlanRecords:
                    - erisaEIN: 12-3456789
                      erisaPlanNumber: '001'
                    - erisaEIN: 98-7654321
                      erisaPlanNumber: '002'
                  from: '2025-10-05T12:56:13.1309707+00:00'
                  to: '2025-11-04T12:56:13.1309719+00:00'
                  skip: 0
                  take: 100
              Request with Date Range Only (No EIN/ERISA):
                value:
                  erisaPlanRecords: null
                  from: '2024-01-01T00:00:00'
                  to: '2024-12-31T00:00:00'
                  skip: 0
                  take: 100
              Single ERISA EIN & ERISA Plan Query:
                value:
                  erisaPlanRecords:
                    - erisaEIN: 45-6789012
                      erisaPlanNumber: '003'
                  from: '2025-09-05T12:56:13.1309728+00:00'
                  to: '2025-10-05T12:56:13.1309729+00:00'
                  skip: 0
                  take: 100
              Invalid Scenario - Missing Dates and ERISA Data:
                value:
                  erisaPlanRecords: []
                  from: null
                  to: null
                  skip: 0
                  take: 100
          application/*+json:
            schema:
              $ref: '#/components/schemas/ParticipantStatusViewModel'
            examples:
              Standard Request with ERISA EIN & ERISA Plan Number:
                value:
                  erisaPlanRecords:
                    - erisaEIN: 12-3456789
                      erisaPlanNumber: '001'
                    - erisaEIN: 98-7654321
                      erisaPlanNumber: '002'
                  from: '2025-10-05T12:56:13.1309707+00:00'
                  to: '2025-11-04T12:56:13.1309719+00:00'
                  skip: 0
                  take: 100
              Request with Date Range Only (No EIN/ERISA):
                value:
                  erisaPlanRecords: null
                  from: '2024-01-01T00:00:00'
                  to: '2024-12-31T00:00:00'
                  skip: 0
                  take: 100
              Single ERISA EIN & ERISA Plan Query:
                value:
                  erisaPlanRecords:
                    - erisaEIN: 45-6789012
                      erisaPlanNumber: '003'
                  from: '2025-09-05T12:56:13.1309728+00:00'
                  to: '2025-10-05T12:56:13.1309729+00:00'
                  skip: 0
                  take: 100
              Invalid Scenario - Missing Dates and ERISA Data:
                value:
                  erisaPlanRecords: []
                  from: null
                  to: null
                  skip: 0
                  take: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NoticeParticipantsRequestStatusView'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
  /api/v1/Participants/upload-pdf:
    post:
      tags:
        - Participants
      summary: Upload PDF File
      description: >-
        Accept PDF uploads, validate, store files, and return URLs for use in
        API requests.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
            encoding:
              file:
                style: form
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validation'
        '413':
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validation'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: string
components:
  schemas:
    Auth0ClientCredentialsTokenRequest:
      required:
        - client_id
        - client_secret
      type: object
      properties:
        client_id:
          minLength: 1
          type: string
        client_secret:
          minLength: 1
          type: string
      additionalProperties: false
    Auth0TokenSuccess:
      type: object
      properties:
        access_token:
          type: string
          nullable: true
        expires_in:
          type: integer
          format: int32
        token_type:
          type: string
          nullable: true
      additionalProperties: false
    ErisaPlanViewModel:
      type: object
      properties:
        erisaEIN:
          type: string
          nullable: true
        erisaPlanNumber:
          type: string
          nullable: true
      additionalProperties: false
    FileUploadData:
      type: object
      properties:
        fileName:
          type: string
          nullable: true
        fileUrl:
          type: string
          nullable: true
      additionalProperties: false
    FileUploadResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/FileUploadData'
        message:
          type: string
          nullable: true
      additionalProperties: false
    NoticeParticipantResponse:
      type: object
      properties:
        noticeParticipantRequestId:
          type: string
          format: uuid
      additionalProperties: false
    NoticeParticipantsRequestStatusView:
      type: object
      properties:
        noticeParticipantRequestId:
          type: string
          description: Unique identifier for the notice participant request.
          format: uuid
        erisaEIN:
          type: string
          description: >-
            ERISA Employer Identification Number associated with the plan
            sponsor.
          nullable: true
        erisaPlanNumber:
          type: string
          description: ERISA plan number associated with the participant's plan.
          nullable: true
        externalReferenceId:
          type: string
          description: >-
            External Reference Id passed in the rollout notice request. Empty
            string if it was not provided
          nullable: true
        reason:
          type: string
          description: 'The reason the rollout is being requested. Valid values: SBR or TERM'
          nullable: true
        firstName:
          type: string
          description: Participant First Name
          nullable: true
        lastName:
          type: string
          description: Participant Last Name
          nullable: true
        ssn:
          maxLength: 9
          minLength: 0
          type: string
          description: >-
            Participant SSN passed in the rollout notice request. Empty string
            if it was not provided
          nullable: true
        addressLine1:
          type: string
          description: Participant Address Line 1
          nullable: true
        addressLine2:
          type: string
          description: Participant Address Line 2
          nullable: true
        city:
          type: string
          description: Participant City
          nullable: true
        state:
          type: string
          description: Participant State
          nullable: true
        zip:
          type: string
          description: Participant Zip
          nullable: true
        countryCode:
          type: string
          description: Participant Country Code
          nullable: true
        totalBalance:
          type: number
          description: Participant Total Balance. Required For TERM
          format: double
          nullable: true
        vestedBalance:
          type: number
          description: Participant Vested Balance. Required For SBR
          format: double
          nullable: true
        deliveryStatus:
          type: string
          description: "Delivery Statuses:\r\n                        <ul>\r\n                            <li>Pending: – a request for the rollout has been accepted and is going through Plan Notices internal processes.</li> \r\n                            <li>Sent: The request has been mailed</li>\r\n                            <li>Success: The mail was successfully delivered</li>\r\n                            <li>ReturnToSender: The mail could not be delivered and was returned to the sender by the postal service.</li>\r\n                            <li>Undeliverable: The mail could not be delivered and was not returned (e.g., due to an invalid address or recipient refusal).</li>\r\n                        </ul>"
          nullable: true
        noticeId:
          type: string
          description: The NoticeId created for the Rollout
          format: uuid
          nullable: true
        gracePeriod:
          type: integer
          description: >-
            The amount of time the participant have to respond to the rollout
            notice
          format: int64
          nullable: true
        gracePeriodExpiration:
          type: string
          description: >-
            The exact date and time when the participant's response deadline for
            the rollout notice expires.
          format: date-time
          nullable: true
        skipped:
          type: boolean
          description: >-
            Indicates whether the participant was skipped during the processing
            of the notice participant request.
        skippedReason:
          type: string
          description: >-
            Specifies the reason why the participant was skipped during the
            notice participant request processing.
          nullable: true
      additionalProperties: false
    Participant:
      required:
        - addressLine1
        - balanceAsOf
        - city
        - erisaEIN
        - erisaPlanName
        - erisaPlanNumber
        - firstName
        - gracePeriod
        - helpAddressLine1
        - helpCity
        - helpName
        - helpPhone
        - helpState
        - helpZip
        - lastName
        - noticeFileContentUrl
        - noticeLogoUrl
        - planSponsorCompany
        - reason
        - state
        - zip
      type: object
      properties:
        erisaEIN:
          minLength: 1
          pattern: ^\d{2}-\d{7}$
          type: string
          description: Erisa EIN must be in the format XX-XXXXXXX (e.g., 12-3456789)
        erisaPlanNumber:
          minLength: 1
          pattern: ^\d{3}$
          type: string
          description: Erisa Plan Number must be exactly 3 digits (e.g., 123).
        erisaPlanName:
          minLength: 1
          type: string
          description: Erisa Plan Name
        planSponsorCompany:
          minLength: 1
          type: string
          description: Plan Sponsor Company
        externalReferenceId:
          maxLength: 100
          minLength: 0
          type: string
          description: External reference ID associated with the rollout notice.
          nullable: true
        reason:
          minLength: 1
          pattern: ^(SBR|TERM)$
          type: string
          description: 'The reason the rollout is being requested. Valid values: SBR or TERM'
        firstName:
          maxLength: 100
          minLength: 0
          type: string
          description: Participant First Name
        lastName:
          maxLength: 100
          minLength: 0
          type: string
          description: Participant Last Name
        ssn:
          maxLength: 11
          minLength: 0
          pattern: ^(?:\d{9}|\d{3}-\d{2}-\d{4})$
          type: string
          description: >-
            SSN in 9-digit or XXX-XX-XXXX format. Required if
            ExternalReferenceId is empty.
          nullable: true
        addressLine1:
          minLength: 1
          type: string
          description: Participant Address Line 1
        addressLine2:
          type: string
          description: Participant Address Line 2
          nullable: true
        city:
          minLength: 1
          type: string
          description: Participant City
        state:
          minLength: 1
          type: string
          description: Participant State
        zip:
          minLength: 1
          type: string
          description: Participant Zip
        countryCode:
          pattern: ^$|^US$
          type: string
          description: Participant Country Code (must be 'US' if provided).
          nullable: true
        totalBalance:
          type: number
          description: Participant Total Balance. Required for TERM.
          format: double
        vestedBalance:
          type: number
          description: Participant Vested Balance. Required for SBR.
          format: double
          nullable: true
        balanceAsOf:
          type: string
          description: Balance as of
          format: date-time
        gracePeriod:
          type: integer
          description: >-
            The amount of time the participant has to respond to the rollout
            notice.
          format: int64
          default: 30
        noticeLogoUrl:
          minLength: 1
          type: string
          description: Notice Logo Url
        noticeFileContentUrl:
          minLength: 1
          type: string
          description: Notice File Content Url
        helpName:
          minLength: 1
          type: string
          description: >-
            The name of the entity the participant should contact for
            assistance.
        helpPhone:
          minLength: 1
          type: string
          description: The phone number the participant should call for help.
        helpWebsite:
          type: string
          description: The website the participant should visit for help.
          nullable: true
        helpEmail:
          type: string
          description: The email address the participant should use for help.
          nullable: true
        helpAddressLine1:
          minLength: 1
          type: string
          description: Help Address Line 1
        helpAddressLine2:
          type: string
          description: Help Address Line 2
          nullable: true
        helpCity:
          minLength: 1
          type: string
          description: Help City
        helpState:
          minLength: 1
          type: string
          description: Help State
        helpZip:
          minLength: 1
          type: string
          description: Help Zip
        helpCountryCode:
          pattern: ^$|^US$
          type: string
          description: Help Country Code (must be 'US' if provided).
          nullable: true
      additionalProperties: false
    ParticipantStatusViewModel:
      type: object
      properties:
        erisaPlanRecords:
          type: array
          items:
            $ref: '#/components/schemas/ErisaPlanViewModel'
          nullable: true
        from:
          type: string
          description: Start of the date range filter (in UTC).
          format: date-time
          nullable: true
        to:
          type: string
          description: End of the date range filter (in UTC).
          format: date-time
          nullable: true
        skip:
          type: integer
          description: Number of records to skip before returning results.
          format: int32
          nullable: true
        take:
          type: integer
          description: Maximum number of records to return.
          format: int32
          nullable: true
      additionalProperties: false
    Validation:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          nullable: true
        traceId:
          type: string
          nullable: true
      additionalProperties: false
